Developer CD Series 1994 August: Tool Chest/Dev.CD Aug 94.toast/New System Software Extensions/OpenDoc A6/OpenDoc Parts Framework/OPF/Found/FWString/Include/FWStrs.h

C/C++ Source or Header | 1994-04-21 | 23.2 KB | 726 lines | [TEXT/MPS ]

#ifndef FWSTRS_H
#define FWSTRS_H
//========================================================================================
//
//    File:                FWStrs.h
//    Release Version:    $ 1.0d1 $
//
//    Creation Date:        3/28/94
//
//    Copyright:    © 1994 by Apple Computer, Inc., all rights reserved.
//
//========================================================================================

#ifndef FWSTDDEF_H
#include "FWStdDef.h"
#endif

#ifndef FWEXCDEF_H
#include "FWExcDef.h"
#endif

#ifndef FWCHARIT_H
#include "FWCharIt.h"
#endif

#ifndef FWCHARAC_H
#include "FWCharac.h"
#endif

//========================================================================================
// Forward Declarations
//========================================================================================

class FW_CStringReader;
class FW_CStringWriter;
class FW_CStringTool;
class FW_CStringArchiver;

//========================================================================================
//    CLASS FW_CString
//
//    String class implementations must satisfy the following requirements:
//
//    1) The string representation is kept in memory.
//    2) The string representation is contiguous.
//    3) The string is NUL-terminated.
//
//    Characters in strings may occupy one, two, and possibly more bytes.
//  The number of characters in the string is therefore not necessarily
//    equal to the number of bytes in the string.
//
//    Since characters may be variable size, there is no general way to directly access a
//    character given it's position.  Thus, it is crucial to use iterators to access the
//    contents of a string such that position state information can be maintained.
//
//    The "length" of the string is measured in characters.
//  The "byteLength" of the string is measured in bytes.
//  The "capacity" of the string is measure in bytes.
//
//========================================================================================

class FW_CString : public _FW_CAutoDestructObject
{
public:

    friend class FW_CStringReader;
    friend class FW_CStringWriter;
    friend class FW_CStringTool;
    friend class FW_CStringArchiver;

    FW_DECLARE_CLASS

    ~FW_CString();
    FW_CString();
    FW_CString(const FW_CString &string);

    FW_CString& operator=(const FW_CString& string);
    FW_CString& operator=(const FW_Char* string);

    FW_CharacterCount GetLength() const;

    FW_ByteCount GetByteLength() const;

    FW_ByteCount GetCapacity() const;

    operator const FW_Char*() const;
        // Return a pointer to the first character in the string.
        // Strings must be contiguous storage, and NUL-terminated!

    virtual FW_ByteCount GrowCapacity(FW_ByteCount capacityNeeded) = 0;
        // Expand the string, if necessary to capacityNeeded.
        // Return the new capacity of the string, which may be less than capacityNeeded!
        // The capacity of a string is never reduced (except by deleting the string).

    FW_Char operator[](FW_CharacterPosition position) const;
        // Retrieve character at given position.
        // Cannot be used on LHS of assignment.
        // The NUL-terminator at position=fLength cannot be accessed.

    void Retrieve(FW_Char* items,
                    FW_CharacterCount numberItems,
                    FW_CharacterPosition position) const;
        // Retrieve numberItems of characters starting at position.

    void Delete(FW_CharacterCount numberItems,
                        FW_CharacterPosition position);
        // Delete numberItems characters, starting at position.

    void Replace(const FW_Char* items,
                        FW_CharacterCount numberItems,
                        FW_CharacterPosition position);
        // Replace numberItems of items starting at position.

    void Insert(const FW_Char* items,
                FW_CharacterCount numberItems,
                FW_CharacterPosition position);
        // Insert characters into string just before the character at positition.
        // Insert at position GetLength() appends the characters.
        // Insert at position 0 prepends the characters.

    void Insert(const FW_CString &string, FW_CharacterPosition position);
        // Insert string at position.

    void Export(char* buffer) const;
        // Copy contents of this string to external buffer.
        // buffer will contain nul-terminated string.
        // It is client's responsibilitiy to ensure buffer is large enough.

    void ReplaceAll(const FW_CString &string);
        // Replace entire contents of this string with string.

    void ReplaceAll(const FW_Char* items, FW_CharacterCount numberItems);
        // Replace entire contents of this string with items.

    void ReplaceAll(const FW_Char* string);
        // Replace entire contents of this string with (nul-terminated) string.

    void Append(const FW_CString &string);
        // Append string onto end of this string.

    void Append(const FW_Char* items, FW_CharacterCount numberItems);
        // Append items onto end of this string.

    void Append(const FW_Char* string);
        // Append (nul-terminated) string onto end of this string.

    void Append(FW_Char character);
        // Append a single character onto the end of this string.

    void Prepend(const FW_Char* items, FW_CharacterCount numberItems);
        // Prepend items onto beginning of this string.

    void Prepend(const FW_CString &string);
        // Prepend string onto beginning of this string.

    void Truncate(FW_CharacterPosition position);
        // Truncate string at position.  Truncate(0) clears string.

    FW_CString& operator+=(const FW_CString &string);
        // Append string onto the end of this string.

    FW_CString& operator+=(const FW_Char* items);
        // Append (nul-terminated) items onto the end of this string.

    FW_CString& operator+=(FW_Char character);
        // Append a single character onto the end of this string.

    // ----- StringTool functions, passed through to current StringTool
    //       These functions are convenience functions only, and will
    //         work correctly only if both strings are of the same locale.

    void ToUpper();
    void ToLower();

    FW_Boolean Substitute(const FW_CString &searchString,
                        const FW_CString &substitutionString);

    FW_Boolean FindSubString(const FW_CString &subString,
                             FW_CharacterPosition &foundPosition,
                             FW_CharacterPosition startPosition=0) const;

    FW_Boolean FindCharacter(FW_Char character,
                             FW_CharacterPosition &foundPosition,
                             FW_CharacterPosition startPosition=0) const;

    FW_Boolean FindWhiteSpace(FW_CharacterPosition &foundPosition,
                            FW_CharacterPosition startPosition=0) const;

    FW_Boolean FindNonWhiteSpace(FW_CharacterPosition &foundPosition,
                                FW_CharacterPosition startPosition=0) const;

    FW_Boolean operator==(const FW_CString &string) const;
    FW_Boolean operator!=(const FW_CString &string) const;
    FW_Boolean operator<(const FW_CString &string) const;
    FW_Boolean operator>(const FW_CString &string) const;
    FW_Boolean operator<=(const FW_CString &string) const;
    FW_Boolean operator>=(const FW_CString &string) const;

#ifdef FW_BUILD_MAC
public:

    // ----- 'Pascal' strings for Macintosh toolbox

    void ExportPascal(FW_PascalChar* buffer) const;
        // Copy contents of this string to external 'pascal' buffer.
        // buffer will contain pascal string string with length byte at buffer[0].
        // It is client's responsibilitiy to ensure buffer is large enough.

    void ReplaceAll(const FW_PascalChar* string);
        // Replace entire contents of this string with pascal string.
#endif

protected:

    void SetLength(FW_CharacterCount characters, FW_ByteCount bytes);

    FW_Byte* fRepresentation;

    FW_CharacterCount    fLength;
        // Cached length.
        // Must always be kept up to date, since GetLength is nonvirtual inline.

#ifdef  FW_VARIABLE_WIDTH_CHARACTERS
    FW_ByteCount    fByteLength;
        // Cached length in bytes.
        // Must always be kept up to date, since GetByteLength is nonvirtual inline.
#endif

    FW_ByteCount    fCapacity;
        // Cached capacity.
        // Must always be kept up to date, since GetCapacity is nonvirtual inline.

private:

    int Compare(const FW_CString &string) const;
        // An implementation method.  Clients use comparision operators.

};

//========================================================================================
//    CLASS FW_TBoundedString
//========================================================================================

template <int tCapacity>
class FW_TBoundedString : public FW_CString
{
public:

    FW_DECLARE_CLASS

    ~FW_TBoundedString();
    FW_TBoundedString();
    FW_TBoundedString(const FW_TBoundedString<tCapacity> &string);
    FW_TBoundedString(const FW_CString &string);
    FW_TBoundedString(const FW_Char *items, FW_CharacterCount numberItems);
    FW_TBoundedString(const FW_Char *items);

    FW_CString& operator=(const FW_TBoundedString<tCapacity> &string);
    FW_CString& operator=(const FW_CString& string);
    FW_CString& operator=(const FW_Char* string);

    virtual FW_ByteCount GrowCapacity(FW_ByteCount capacityNeeded);
        // Return tCapacity*FW_kMedianCharacterSize.  The capacity of bounded strings never changes.

private:

    FW_Byte            fStorage[tCapacity*FW_kMedianCharacterSize+sizeof(FW_Char)];
        // Must leave room for a NUL word
};

typedef FW_TBoundedString<32> FW_CString32;
typedef FW_TBoundedString<255> FW_CString255;

//========================================================================================
//    CLASS FW_CDynamicString
//========================================================================================

class FW_CDynamicString : public FW_CString
{
public:

    FW_DECLARE_CLASS

    ~FW_CDynamicString();
    FW_CDynamicString(FW_ByteCount capacity=0);
    FW_CDynamicString(const FW_CDynamicString &string);
    FW_CDynamicString(const FW_CString &string);
    FW_CDynamicString(const FW_Char *items, FW_CharacterCount numberItems);
    FW_CDynamicString(const FW_Char *items);

    FW_CString& operator=(const FW_CDynamicString &string);
    FW_CString& operator=(const FW_CString& string);
    FW_CString& operator=(const FW_Char* string);

    virtual FW_ByteCount GrowCapacity(FW_ByteCount capacityNeeded);
        // Expand the string, if necessary to capacityNeeded.
        // Return the new capacity of the string.
        // The capacity of a string is never reduced (except by deleting the string).

protected:

    void Resize(FW_ByteCount newCapacity);

private:

    void AllocateRepresentation(FW_ByteCount capacity);
};

//========================================================================================
//    CLASS FW_CStringReader
//========================================================================================

class FW_CStringReader : public FW_CTextReader
{
public:
    FW_CStringReader(const FW_CString &string);
    FW_CStringReader(const FW_CString &string,
                                FW_CharacterPosition start,
                                FW_CharacterCount   length);

protected:

    virtual void DoGetNextBuffer();
        // Get another buffer from text data structure.
        // Updates fStart and fLimit.
        // Must ensure that fStart<=fLimit

    virtual void DoGetPreviousBuffer();
        // Gets previous buffer from text data structure.
        // Updates fStart and fLimit.
        // Must ensure that fStart<=fLimit

};

//========================================================================================
//    CLASS FW_CStringWriter
//========================================================================================

class FW_CStringWriter : public FW_CTextWriter
{
public:
    enum {kDefaultExpansion=32};

    ~FW_CStringWriter();
    FW_CStringWriter(FW_CString &string,
                     FW_TextWriterMode mode=FW_kTextAppend,
                     unsigned short expansion=kDefaultExpansion);

protected:

    virtual void DoFlushAndGetNextBuffer();
        // Flush the current buffer.
        // Get another buffer from string, update fNext and fLimit.

    void FlushAndUpdateText();
        // Flush the current buffer.
        // Do whatever may be necessary to restore text structure to valid state,
        // ... e.g. restore NUL termination, cached length member, etc.
        // This method is called from destructor.

    FW_CString    &fString;
    unsigned short fExpansion;
    FW_Byte *fBuffer;
};

//========================================================================================
//    CLASS FW_CString
//========================================================================================

//----------------------------------------------------------------------------------------
//    FW_CString::GetLength
//----------------------------------------------------------------------------------------

inline FW_CharacterCount FW_CString::GetLength() const
{
    return fLength;
}

//----------------------------------------------------------------------------------------
//    FW_CString::GetByteLength
//----------------------------------------------------------------------------------------

inline FW_ByteCount FW_CString::GetByteLength() const
{
#ifdef  FW_VARIABLE_WIDTH_CHARACTERS
    return fByteLength;
#else
    return fLength*sizeof(FW_Char);
#endif
}

//----------------------------------------------------------------------------------------
//    FW_CString::GetCapacity
//----------------------------------------------------------------------------------------

inline FW_ByteCount FW_CString::GetCapacity() const
{
    return fCapacity;
}

//----------------------------------------------------------------------------------------
//    FW_CString::SetLength
//----------------------------------------------------------------------------------------

inline void FW_CString::SetLength(FW_CharacterCount characters, FW_ByteCount bytes)
{
    fLength = characters;
#ifdef  FW_VARIABLE_WIDTH_CHARACTERS
    fByteLength = bytes;
    for (i=0; i< sizeof(FW_Char); i++)
    {
        // set 1 byte at a time because some machines (e.g. MC68010) may not allow
        // writing words to odd addresses
        fRepresentation[bytes+i] = 0;
    }
#else
    FW_ASSERT(bytes == characters*sizeof(FW_Char));
    *((FW_Char*)(fRepresentation+bytes)) = FW_kNulCharacter;
#endif
}

//----------------------------------------------------------------------------------------
//    FW_CString::operator const FW_Char*
//----------------------------------------------------------------------------------------

inline FW_CString::operator const FW_Char*() const
{
    return (const FW_Char*) fRepresentation;
}

//----------------------------------------------------------------------------------------
//    FW_CString::operator=
//----------------------------------------------------------------------------------------

inline FW_CString& FW_CString::operator=(const FW_CString& string)
{
    if (&string != this)
        ReplaceAll(string);
    return *this;
}

//----------------------------------------------------------------------------------------
//    FW_CString::operator=
//----------------------------------------------------------------------------------------

inline FW_CString& FW_CString::operator=(const FW_Char* string)
{
    ReplaceAll(string, FW_StringLength(string));
    return *this;
}

//----------------------------------------------------------------------------------------
//    FW_CString::Export
//----------------------------------------------------------------------------------------

inline void FW_CString::Export(FW_Char* buffer) const
{
    FW_BlockMove(fRepresentation, (FW_Byte*) buffer, GetByteLength()+sizeof(FW_Char));
}

#ifdef FW_BUILD_MAC
//----------------------------------------------------------------------------------------
//    FW_CString::ExportPascal
//----------------------------------------------------------------------------------------

inline void FW_CString::ExportPascal(FW_PascalChar* buffer) const
{
    FW_BlockMove(fRepresentation, (FW_Byte*)(buffer+1), fLength);
    buffer[0] = (FW_PascalChar) fLength;
}
#endif

#ifdef FW_BUILD_MAC
//----------------------------------------------------------------------------------------
//    FW_CString::ReplaceAll
//----------------------------------------------------------------------------------------

inline void FW_CString::ReplaceAll(const FW_PascalChar* items)
{
    ReplaceAll((FW_Char*) items+1, items[0]);
}
#endif

//----------------------------------------------------------------------------------------
//    FW_CString::ReplaceAll
//----------------------------------------------------------------------------------------

inline void FW_CString::ReplaceAll(const FW_CString& string)
{
    Replace((const FW_Char*)string, string.fLength, 0);
    Truncate(string.fLength);
}

//----------------------------------------------------------------------------------------
//    FW_CString::ReplaceAll
//----------------------------------------------------------------------------------------

inline void FW_CString::ReplaceAll(const FW_Char* items,
                FW_CharacterCount numberItems)
{
    Replace(items, numberItems, 0);
    Truncate(numberItems);
}

//----------------------------------------------------------------------------------------
//    FW_CString::ReplaceAll
//----------------------------------------------------------------------------------------

inline void FW_CString::ReplaceAll(const FW_Char* items)
{
    ReplaceAll(items, FW_StringLength(items));
}

//----------------------------------------------------------------------------------------
//    FW_CString::Insert
//----------------------------------------------------------------------------------------

inline void FW_CString::Insert(const FW_CString& string,
            FW_CharacterPosition position)
{
    Insert(string, string.fLength, position);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Append
//----------------------------------------------------------------------------------------

inline void FW_CString::Append(const FW_CString& string)
{
    Insert(string, string.fLength, fLength);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Append
//----------------------------------------------------------------------------------------

inline void FW_CString::Append(const FW_Char* items,
            FW_CharacterCount numberItems)
{
    Insert(items, numberItems, fLength);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Append
//----------------------------------------------------------------------------------------

inline void FW_CString::Append(const FW_Char* string)
{
    Insert(string, FW_StringLength(string), fLength);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Append
//----------------------------------------------------------------------------------------

inline void FW_CString::Append(FW_Char character)
{
    Insert(&character, 1, fLength);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Prepend
//----------------------------------------------------------------------------------------

inline void FW_CString::Prepend(const FW_Char* items,
             FW_CharacterCount numberItems)
{
    Insert(items, numberItems, 0);
}


//----------------------------------------------------------------------------------------
//    FW_CString::Prepend
//----------------------------------------------------------------------------------------

inline void FW_CString::Prepend(const FW_CString& string)
{
    Insert(string, string.fLength, 0);
}


//----------------------------------------------------------------------------------------
//    FW_CString::Truncate
//----------------------------------------------------------------------------------------

inline void FW_CString::Truncate(FW_CharacterPosition position)
{
    Delete(fLength - position, position);
}


//----------------------------------------------------------------------------------------
//    FW_CString::operator+=
//----------------------------------------------------------------------------------------

inline FW_CString& FW_CString::operator+=(const FW_CString& string)
{
    Append(string);
    return *this;
}

//----------------------------------------------------------------------------------------
//    FW_CString::operator+=
//----------------------------------------------------------------------------------------

inline FW_CString& FW_CString::operator+=(const FW_Char* string)
{
    Append(string);
    return *this;
}

//----------------------------------------------------------------------------------------
//    FW_CString::operator+=
//----------------------------------------------------------------------------------------

inline FW_CString& FW_CString::operator+=(FW_Char character)
{
    Append(character);
    return *this;
}

//----------------------------------------------------------------------------------------
//    FW_CString::operator[]
//----------------------------------------------------------------------------------------

inline FW_Char FW_CString::operator[](FW_CharacterPosition position) const
{
#ifdef  FW_VARIABLE_WIDTH_CHARACTERS
    return NotYetImplemented();
#else
    return ((FW_Char*)fRepresentation)[position];
#endif
}

//========================================================================================
//    CLASS FW_TBoundedString
//========================================================================================

//----------------------------------------------------------------------------------------
//    FW_TBoundedString<tCapacity>::operator=
//----------------------------------------------------------------------------------------

template <int tCapacity>
inline FW_CString&
FW_TBoundedString<tCapacity>::operator=(const FW_TBoundedString<tCapacity>& string)
{
    if (&string != this)
        ReplaceAll(string);
    return *this;
}

//----------------------------------------------------------------------------------------
//    FW_TBoundedString<tCapacity>::operator=
//----------------------------------------------------------------------------------------

template <int tCapacity>
inline FW_CString&
FW_TBoundedString<tCapacity>::operator=(const FW_CString& string)
{
    ReplaceAll(string);
    return *this;
}

//----------------------------------------------------------------------------------------
//    FW_TBoundedString<tCapacity>::operator=
//----------------------------------------------------------------------------------------

template <int tCapacity>
inline FW_CString&
FW_TBoundedString<tCapacity>::operator=(const FW_Char* string)
{
    ReplaceAll(string, FW_StringLength(string));
    return *this;
}

//========================================================================================
//    CLASS FW_CDynamicString
//========================================================================================

//----------------------------------------------------------------------------------------
//    FW_CDynamicString::operator=
//----------------------------------------------------------------------------------------

inline FW_CString&
FW_CDynamicString::operator=(const FW_CDynamicString& string)
{
    if (&string != this)
        ReplaceAll(string);
    return *this;
}

//----------------------------------------------------------------------------------------
//    FW_CDynamicString::operator=
//----------------------------------------------------------------------------------------

inline FW_CString&
FW_CDynamicString::operator=(const FW_CString& string)
{
    ReplaceAll(string);
    return *this;
}

//----------------------------------------------------------------------------------------
//    FW_CDynamicString::operator=
//----------------------------------------------------------------------------------------

inline FW_CString&
FW_CDynamicString::operator=(const FW_Char* string)
{
    ReplaceAll(string, FW_StringLength(string));
    return *this;
}

//----------------------------------------------------------------------------------------
//    FW_CDynamicString::AllocateRepresentation
//----------------------------------------------------------------------------------------

inline void FW_CDynamicString::AllocateRepresentation(FW_ByteCount capacity)
{
    fRepresentation = new FW_Byte[capacity+sizeof(FW_Char)];
    fCapacity=capacity;
    SetLength(0,0);
}

#endif